From 33aedf83aa9e1c126c7f845c19cc379a75ff4a48 Mon Sep 17 00:00:00 2001 From: robertl Date: Sun, 9 Jul 2006 00:05:21 +0000 Subject: [PATCH] Improvements in xcsv doc. --- xmldoc/chapters/styles.xml | 153 ++++++++++++++++++++++++++++++++++--- xmldoc/formats/xcsv.xml | 3 +- 2 files changed, 144 insertions(+), 12 deletions(-) diff --git a/xmldoc/chapters/styles.xml b/xmldoc/chapters/styles.xml index 7ec225047..8c38a58cc 100644 --- a/xmldoc/chapters/styles.xml +++ b/xmldoc/chapters/styles.xml @@ -4,19 +4,90 @@
Introduction -The format of an XCSV style file is quite simple and designed to be easily -implemented by non-programmers to handle "one-off" babel-ization of various -XCSV (whatever separated values) text files. The format and usage of the -various style directives are described below. +Often it is desirable to add a new file format for "one-off" work (perhaps +you want to export something to a spreadsheet or graphing program) or to read +a format that GPSBabel does not yet support. For suitably simple formats, +this can be done by a user with no programming experience by providing a +GPSBabel style file. + + +For a format to be described by a style file, it must be predictable and +generally readable by humants. Formats with binary or unreadable content +are not good fits for this scheme. It should have: + +A fixed header at the beginning, if it has any at all. This is called a 'prologue'. +Waypoints that are grouped by fixed separators, often a newline. In style file parlance, this is called a 'record'. +Traits of that waypoint described in that record. In the style files, these are called 'fields' and examples may include longitude or a name. +Fields that are grouped by fixed separators, often a comma or a tab. In the style files, this is called the field separator. +A fixed footer at the end, if it has any at all. This is called the 'epilogue'. + + + +Once you have created a style file that describes the file format you have +or want, you must tell GPSBabel to use the xcsv format and have the xcsv +format use that file. If you created a new style file called +"mystyle.style" and you want to write the waypoints from +a GPX file named "mine.gpx" to it, you would issue a command like: +gpsbabel -i gpx -f mine.gpx -o xcsv,style=mystyle.style -f mine.new +You might then examine mine.new to see if it met +your expectations. If not, you could continue to tweak +mystyle.style until it did, rerunning the above +command each time. If 'mystyle' is a format +that describes a popular program or is likely to be of use to others, you can +then share mystyle.style with other GPSBabel users. +Send it along with a coherent descripton to the GPSBabel mailing list for +consideration to be included in a future version. +
+
+Style file overview -The first and foremost important step is understanding how the config +The first and foremost important step is understanding how the style file is laid out itself. The format is: DIRECTIVE<whitespace>VALUE -Where <whitespace> is a space, tab, spaces, tabs, etc... There should -be nothing before the directive. (i.e. not " DIRECTIVE VALUE") +Where <whitespace> is one or more spaces or tabs. There should +be no spaces or tabs at the beginning of the line; all directives start +at the left edge in column zero. + + +An example style format is shown here: + + +# Format: MS S&T 2002/2003 +# Author: Alex Mottram +# Date: 12/09/2002 +# + +DESCRIPTION Microsoft Streets and Trips 2002-2006 +EXTENSION txt + +# +# FILE LAYOUT DEFINITIIONS: +# +FIELD_DELIMITER TAB +RECORD_DELIMITER NEWLINE +BADCHARS ," + +PROLOGUE Name Latitude Longitude Description URL Type Container Diff Terr + +# +# INDIVIDUAL DATA FIELDS, IN ORDER OF APPEARANCE: +# NOTE: MS S&T ONLY IMPORTS DATA, IT DOESN'T EXPORT THIS ANYWHERE SO WE CAN +# HAVE OUR WAY WITH THE FORMATTING. +# +IFIELD SHORTNAME, "", "%s" # Name +IFIELD LAT_DECIMAL, "", "%f" # Latitude +IFIELD LON_DECIMAL, "", "%f" # Longitude +IFIELD DESCRIPTION, "", "%s" # Name 2 (Big Description) +IFIELD URL, "", "%s" # URL +IFIELD GEOCACHE_TYPE, "", "%s" # Geocache Type +IFIELD GEOCACHE_CONTAINER, "", "%s" # Geocache Type +IFIELD GEOCACHE_DIFF, "", "%3.1f" # Geocache Type +IFIELD GEOCACHE_TERR, "", "%3.1f" # Geocache Type + +Each of these lines will be explained in the following sections.
@@ -271,8 +342,8 @@ IFIELDS are use as both input and output. The existence of OFIELDS is primarily to allow more flexible mapping of GPSBabel data to output data (say, for instance, to map the internal GPSBabel "description" variable to two or more fields on output). For all practical purposes, IFIELDS and -OFIELDS are defined the same way in the style file. The following options -are defined: +OFIELDS are defined the same way in the style file. +The following per-field options are defined: @@ -289,6 +360,20 @@ are defined: that only absolute values (never negative) are to be printed. + + + + "optional" is supported only OFIELD tags and indicates that the + field may or may not be available in the source data. If the + field is absent, no trailing field separator is written. + + + This attribute is most useful when paired with "no_delim_before" as + it allows you to concatenate fields without concern on whether those + fields are actually populated or not. + + + @@ -937,9 +1022,55 @@ example:
Examples -For examples on using the XCSV module, please see the +Here is one example style file from the GPSBabel source. + +# gpsbabel XCSV style file +# +# Format: Garmin POI +# Author: Robert Lipe +# Date: 10/07/2005 +# Reference: http://forums.groundspeak.com/GC/index.php?showtopic=110641&st=0&#entry1752204 +# +DESCRIPTION Garmin POI database +# +# +# FILE LAYOUT DEFINITIIONS: +# +FIELD_DELIMITER COMMA +RECORD_DELIMITER NEWLINE +BADCHARS COMMA +SHORTLEN 24 + +# +# INDIVIDUAL DATA FIELDS, IN ORDER OF APPEARANCE: +# +IFIELD LON_HUMAN_READABLE, "", "%08.5f" +IFIELD LAT_HUMAN_READABLE, "", "%08.5f" +IFIELD SHORTNAME, "", "%s" +IFIELD DESCRIPTION, "", "%s" + +OFIELD LON_DECIMAL, "", "%08.5f" +OFIELD LAT_DECIMAL, "", "%08.5f" +OFIELD SHORTNAME, "", "%-.24s" +OFIELD GEOCACHE_TYPE, "", " %-.4s", "no_delim_before,optional" +OFIELD GEOCACHE_CONTAINER, "", "/%-.4s ", "no_delim_before,optional" +OFIELD GEOCACHE_DIFF, "", "(%3.1f", "no_delim_before,optional" +OFIELD GEOCACHE_TERR, "", "/%3.1f)", "no_delim_before,optional" +OFIELD DESCRIPTION, "", "%-.50s" + +When used on a Groundspeak Pocket Query, it will output lines that +look like: + +-76.76234,38.39123,GC5370 Loca/Virt (1.0/1.0),Dude.. Wheres my Limo?? +-90.42345,38.55234,GCC8B Trad/Regu (2.0/2.0),Sweet Reward +-90.81456,38.62456,GC3091 Trad/Regu (1.5/2.0),Matson Hill + +that are suitable for Garmin's POI loader. + + +For additional examples, please see the *.style files in the -style/ subdirectory of GPSBabel. +style/ subdirectory of GPSBabel or at the online source tree.
diff --git a/xmldoc/formats/xcsv.xml b/xmldoc/formats/xcsv.xml index 5b695d793..cc2e9e2ab 100644 --- a/xmldoc/formats/xcsv.xml +++ b/xmldoc/formats/xcsv.xml @@ -1,7 +1,8 @@ This format is a very flexible module that can be used to read or write nearly any plain-text record-based waypoint file. This flexibility is -achieved with "style" files that describe the format of the waypoint files. +achieved by combining this format with "style" files that describe the +format of the waypoint files. There are several formats built in to GPSBabel that use the underlying xcsv -- 2.30.2